######README######
# @@name@@-说明

主要功能包括：

- Config设置
- set-修改组件设置
- get-获取组件数据

# ※ Config设置

```
{
	"name": "$.@@name@@",
    "config": {
        "_id":"",
        "_templ":"child##0",
        "_class":""
    }
}
```

| key          | 说明                                        | 默认值                | 类型     | 组入/更新版本  |
| ------------ | ------------------------------------------- | --------------------- | -------- | -------------- |
| _id          | 组件id，命名尽量唯一，且不包含`.`           | 不需要调用组件        | String   | 1.0=0000.00.00 |
| _data        | 自定义暂存数据，获取组件数据时会被一同返回  | null                  | 开放类型 | 1.0=0000.00.00 |
| _templ | 内容模板                           | 以整个`child`作为模板 | 开放类型 | 1.0=0000.00.00 |
| _class   | 组件的外层样式                          |                       | String   | 1.0=0000.00.00 |

参数补充说明：

### > _id

- 组件id，用于标识组件，用于操作组件（更新/获取数据）
- 推荐格式为`comp##@@name@@<<[所在页面布局]`，如`comp##@@name@@<<Title`、`comp##@@name@@<<Title/Info`
- 如果组件在初始化后并不需要操作，组件id不需要设置，组件id设置为空字符串`""`，视为无效设置
- 组件id尽量唯一，如果不唯一，则同名组件会同时响应
- 组件id尽量不要包含`.`，由于基础库`pubsub-js`的影响，如果命名中含有`.`，则可能引起多个组件被调用的情况，如调用`a`组件时，会同时调用`a.1`和`a.2`等组件

### > _templ

- `_templ`开头的key都会被认为是模板设置
- 当对应值为字符串，且以`$.`开头，(要求Trick2.2版本以后)，会采用对应组件作为模板。此设置仅在页面`xxxUI.json`、`xxxAction.json`配置中生效，其他情况会按照字符串处理
- 当对应值设置为`null`（默认），或者以下设置中出现不能正确获取的情况，都会以整个`child`作为模板。`child`为页面UI设置时的`child`（此组件的内嵌子组件）
- 当对应值为字符串，且以`child##`开头，会选择`child`的第n个子组件作为模板，如`child##2`，则会选择`child`中第3个（0开始）子组件作为模板
- 当对应值为字符串，且以`layout##`开头（Trick2.2及以后版本生效），会以某个页面布局作为模板，如`layout##Theme`，则会选择id为`Theme`的页面布局作为模板
- `child##`和`layout##`都支持深层筛选模式，用`>>`分隔，如`child##_BoxForm>>_CompInput`，层级是按jsx嵌套层级而定的
- 当对应值为字符串，且不包含以上特殊开头，会认为是文字，且会自动进行翻译
- 当对应值为对象`{}`，表示详细设置模式，固定格式为`{"_templ":"","_config":{},"_configDeep":{}}`。`_templ`对应模板选择（以上类型适用）；`_config`会自动合并进模板的最外层`config`；`_configDeep`会自动合并进模板的里层`config`，具体格式为`{"position 1":{},"position 2":{}}`，`key`为定位设置，使用`>>`分割，可以采用`序号`或者`组件名`进行选择，如`0>>div>>_Boxflex`，表示`第0个组件`>>`名称为div的组件`>>`名称为_Boxflex的组件`；当`_templ`为文字，会将`_config`作为翻译设置（变量替换），`_configDeep`无效
- 当对应值为数组`[]`，可以内嵌以上类型，会以此数组顺序编排模板

### > _text

- `_text`开头的key都会被认为是文字设置
- 当对应值为字符串，都会自动进行翻译
- 推荐需要翻译的文字格式为`**[所在页面布局]>>[文字提示]`，如`**Form>>occupation`，`**Form/occupation>>project manager`
- 当对应值为对象`{}`，表示详细设置，固定格式为`{"_text":"xxx", "key 1":"value", "key 2":"value"}`，`_text`对应文字设置，其他设置作为翻译设置（变量替换）

### > _src

- `_src`开头的key都会被认为是资源文件路径设置
- 以`//`开头，会自动定位到工程图片存放位置
- 页面运行时，`//`会自动定位到`Code/Assets`
- 本组件单独运行时，`//`会自动定位到当前组件的`test`文件夹
- `test`文件夹需要手动创建，且仅用于当前组件单独测试运行

### > _class

- `_class`开头的key一般为html的class设置
- 推荐采用`tailwindcss`的类进行设置，如果需要覆盖组件固有样式设置，需要在类名前加`!`，如`!w-full`
- 可以采用页面自定义的`class`进行设置，如果需要覆盖组件固有样式设置，需要设置`!important`
- 文字、边距大小、颜色等，尽量采用主题css文件的变量，自定义`class`中可以采用`var(xxx)`进行设置；`tailwindcss`可以采用`[xxx]`进行设置，如`gap-[--Theme-Gap]`

### > _on

- `_on`开头的key一般为事件回调的设置
- 当对应值设置为字符串，且以`pack##`开头，则自动调用其上层的`Pack组件`，如`_PackForm`等；这类`Pack组件`向所有下层组件传递回调地址、部分数据；`pack##`后面可以设置调用`pack组件`的`_action`，如`pack##commit`，则表示调用上层`Pack组件`的`commit`动作
- Trick2.2新增，当对应值设置为字符串，且以`css##`开头，则表示css class开关模式，元素筛选设置与class用`>>`隔开，如`css##.Page-Title>>class_1 class_2`，表示通过`document.querySelector`筛选`.Page-Title`，若元素中同时存在`class_1 class_2`这两个class，则清理，否则补充不存在的class。在测试模式下，由于事件可能会触发2次（React机制），此设置会转换两次，所以表面上可能不生效
- Trick2.2新增，当对应值设置为字符串，且以`css add##`开头，则表示`css class`追加模式，设置格式同`css##`
- Trick2.2新增，当对应值设置为字符串，且以`css remove##`开头，则表示`css class`清理模式，设置格式同`css##`
- Trick2.2新增，当对应值设置为字符串，且以`style##`开头，则表示`style`样式设置模式，元素筛选设置与`style设置`用`>>`隔开，多个样式设置用`;`隔开，如`style##.Page-Title>>color:#fff;width:100% !important;`，表示通过`document.querySelector`筛选`.Page-Title`，并设置样式
- 当对应值设置为字符串，则表示以`id`的方式调用其他组件，或者页面Action的函数，页面Action的函数以`act##`开头，如`act##Language_Change`
- 当对应值为函数，则表示调用此函数，此类型用于组件测试，在制作页面时，无法使用此种类型
- 当对应值为对象`{}`，表示详细设置，一般情况下，事件回调时，返回的数据为整个组件的数据，如果希望详细配置返回的数据，则应该采用对象类型；固定格式为`{"_call":"","_data":{}}`，`_call`对应回调目标的设置，`_data`对应具体回调数据的设置；`_data`固定格式为`{"key 1":"value 1","key 2":"value 2"}`，最外层的`key`对应的`value`支持动态注入语法；`value`的动态语法为，`get##`开头表示从本组件数据中获取，`pack##`开头表示从`Pack组件`传递的数据中获取，且允许使用`>>`定位深层的数据，如`get##key_1>>key_2`

- 当对应值为数组`[]`，可以内嵌以上类型，组件会执行多个回调（异步调用，无法保证顺序）
- Trick2.2新增，默认情况下，`event`事件会冒泡传递（上层HTML节点也会响应），若希望不冒泡传递，可以采用`_isStop`设置，`{"_isStop":true,"_call":"xxx"}`。若希望设置多个回调，可以设置为`{"_isStop":true,"_call":["xxx", "xxx"]}`。若关闭冒泡传递，`_BoxPage`对SPA网页的`a`捕获也会失效

# ※ set-修改组件设置

组入版本：组件通用机制

修改组件传递的参数与`Config设置`相同，可省略不需要更新的数据

- 如果某项数据为数组`[]`，且希望为追加模式，则在`key`前追加`push##`前缀，例如`push##key`
- 如果某项数据为数组`[]`，且仅希望替换某个位置的数据，则在`key`前追加`push##序号##`前缀，例如`push##1##key`
- 如果某项数据为对象类型`{}`，默认情况下，组件会补充合并省略的字段，如果希望不合并旧的设置，可以在`key`前追加`nec##`前缀
- `nec##`和`push##`前缀不能同时存在
- 以上前缀只适用于`config`对象的最外层的`key`
- 如果新设置的值不符合类型要求，会采用组件默认的值进行替换，而非保留初始化的组件设置

### > 页面Action调用例子

`页面Action`需要通过`_BrokerUI`模块进行组件设置，其中`_config`对应设置的数据

```
{
    "name":"_BrokerUI",
    "param":{
        "_id":"组件id",
        "_config":{
        	"key":"value"
        }
    }
}
```

补充说明：

`_config`设置中，最外层的`key`对应的`value`支持模块参数语法，如`{"key":"get##$value"}`，则表示从`passParam`中获取`$value`

- 如果希望设置的值为固定值，则直接设置对应类型的值即可
- 如果希望从`passParam`中动态获取值作为设置的值，则请以`get##key`作为设置值
- 如果想要获取的值在`passParam`的里层（嵌套json），则请以`>>`定位，如`get##key_1>>key_2`

### > 页面UI调用例子

如果希望其他组件事件触发时，更新此组件的设置，可在对应组件的事件回调中设置以下参数，其中`_data`对应设置的数据

```
"_onXXX"：{
    "_call":"组件id"
    "_data":{
        "key":"value"
    }
}
```

补充说明：

`_data`设置中，最外层的`key`对应的`value`支持动态注入语法，如`{"key":"get##key 1"}`，表示从触发回调的组件数据中获取`key 1`的数据

- 如果希望从触发回调的组件数据中获取值，采用`get##`开头

- 如果希望从触发回调的组件的上层`Pack组件`传递的数据中获取值，采用`pack##`开头

- 在采用`get##`、`pack##`开头时，允许采用`>>`定位深层的数据，如`get##key_1>>key_2`

- 动态注入语法只适合`_data`对象最外层值的设置，深层设置是不会被处理的

    ```
    {
    	"key 1":"get##key 1",						#动态注入值
    	"key 2":{
    		"key 2-1":"get##key 2"                  #保持'get##key 2'的值
    	}
    }
    ```

# ※ get-获取组件数据

组入版本：组件通用机制

`页面Action`需要通过`_BrokerUI`模块获取，返回的数据为以上`config设置`中的所有数据

数据会自动插入`passParam`中，插入字段为`_resultKey`对应的值。当`_resultKey`对应值为空字符串`""`，会将整个`passParam`清空，并写入数据

```
{
    "name":"_BrokerUI",
    "param":{
    	"_id":"组件id",
        "_isFailResend":false,
        "_isSync":true,
        "_config":{
            "_action":"get",
            "_resultKey":""
        }
     }
}
```

# ◎ 模块单独测试

在工程根目录，运行shell指令

```
python3 Christmas/Christmas.py ShellExcute/Build#Component @@name@@
```

也可以通过`Christmas插件`运行`ShellExcute>>Build#Component`，并在插件打开的终端中输入`@@name@@`

`Sample.html`，`Sample.js`是专门用于单独测试的代码

# ◎ 更新列表

**1.0=0000.00.00**

- 组件建立
######README######


######README-en######
# @@name@@-explain

The main functions include:

- Config Settings
- set-modify component settings
- get-get component data

# ※ Config Settings

```
{
	"name": "$.@@name@@",
    "config": {
        "_id":"",
        "_templ":"child##0",
        "_class":""
    }
}
```

| key          | Description                                                  | Default                                | Type      | Add/Update     |
| ------------ | ------------------------------------------------------------ | -------------------------------------- | --------- | -------------- |
| _id          | Component id, the name should be as unique as possible, and do not contain `.` | No need to call components             | String    | 1.0=0000.00.00 |
| _data        | Custom temporary storage data, which will be returned together when obtaining component data | null                                   | Open type | 1.0=0000.00.00 |
| _templ       | Content template                                             | Take the whole `child` as the template | Open type | 1.0=0000.00.00 |
| _class   | Outer style of the component                        |                                        | String    | 1.0=0000.00.00 |

Parameter Supplementary Description:

### > _id

- Component id, used to identify components, used to operate component (update/obtain data)

- The recommended format is `comp##@@name@@<<[page layout]`, such as `comp##@@name@@<<Title`, `comp##@@name@@<<Title/Info`

- If the component does not need to be operated after initialization, the component id does not need to be set, and the component id is set to an empty string `""`, it is considered an invalid setting

- The component id is as unique as possible. If it is not unique, the component of the same name will respond at the same time

- Try not to include `.` in the component id, due to the influence of the basic library `pubsub-js`, if the name contains `.`, which may cause multiple components to be called. For example, when calling the `a` component, components such as `a.1` and `a.2` will be called at the same time

### > _templ

- The key at the beginning of `_templ` will be regarded as a template setting

- When the corresponding value is a string and starts with `$.` (required for Trick2.2 version and later), the corresponding component is used as a template. This setting only takes effect in the `xxxUI.json` `xxxAction.json` page configuration, while other situations will be processed as a string

- When the corresponding value is set to `null` (default), or the following settings cannot be obtained correctly, the whole `child` will be used as the template. And  `child` is the `child` set to the page UI (the embedded subcomponent of this component)

- When the corresponding value is a string and begins with `child##`, the nth subcomponent of `child` will be selected as a template, such as `child##2`, the third (starting from 0) subcomponent of `child` will be selected as the template

- When the corresponding value is a string and begins with `layout##` (Trick2.2 and later versions take effect), a page layout will be used as a template, such as `layout##Theme`, and the page layout with id  `Theme` will be selected as the template
- `child##` and `layout##` both support deep filtering mode, separated by `>>`, such as `child##_BoxForm>>_CompInput`, and the hierarchy is determined by the jsx nested hierarchy

- When the corresponding value is a string and does not contain the above special beginning, it will be regarded as text and will be automatically translated

- When the corresponding value is the object `{}`, it indicates the detailed setting mode, and the fixed format is `{"_templ":"","_config":{},"_configDeep":{}}`. `_templ` corresponds to the template selection (the above types are applicable); `_config` will automatically merge into the outermost layer of the template `config`; `_configDeep` will automatically merge into the inner layer of the template `config`, and the specific format is `{"position 1":{},"position 2":{}}`, `key` is the positioning setting, using `>>` locate, you can use `index number` or `component name` to select, such as `0>>div>>_Boxflex`, indicating `0th component`>>`div`>>`component named _Boxflex`; when `_templ` is text, `_config` will be used as a translation setting (variable replacement), and `_configDeep` is invalid

- When the corresponding value is the array `[]`, the above type can be embedded, and the template will be arranged in the order of this array

### > _text

- The key at the beginning of `_text` will be regarded as a text setting

- When the corresponding value is a string, it will be automatically translated

- The recommended text format that needs to be translated is `**[page layout]>>[text prompt]`, such as `**Form>>occupation`, `**Form/occupation>>project manager`

- When the corresponding value is the object `{}`, it indicates the detailed settings. The fixed format is `{"_text":"xxx", "key 1":"value", "key 2":"value"}`, `_text` corresponds to the text settings, and other settings are translated Settings (variable replacement)

### > _src

- The key starting with `_src` will be regarded as the resource file path setting

- Starting with `//`, it will automatically locate the storage location of the project picture

- When the page is running, `//` will automatically locate to `Code/Assets`

- When this component is running alone, `//` will automatically locate the `test` folder of the current component

- The `test` folder needs to be created manually and is only used for the separate test run of the current component

### > _class

- The key at the beginning of `_class` is generally set to the class of html

- It is recommended to use the class of `tailwindcss` for setting. If you need to overwrite the inherent style settings of the component, you need to add  `!`  before the class name, such as `!w-full`

- You can use the page-customized `class` to set it. If you need to overwrite the inherent style settings of the component, you need to set it `!important`

- Text, margin size, color, etc.Try to use the variables of the theme css file, custom `class` can be set by `var(xxx)`; `tailwindcss` can be set by `[xxx]`, such as `gap-[--Theme-Gap]`

### > _on

- The key at the beginning of `_on` is generally the setting of the event callback

- When the corresponding value is set to a string and starts with `pack##`, it automatically calls its upper `Pack component`, such as `_PackForm`, etc.; this kind of `Pack component` passes the callback address and some data to all lower components; It can be set the `_action` of calling `Pack component` after `pack##` , such as `pack##commit`, which indicates the `commit` action of calling the upper `Pack component`

- Trick2.2 add, When the corresponding value is set to a string and begins with `css##`, it indicates the css class switch mode, and the element filtering settings are separated from class by `>>`, such as `css##. Page-Title>>class_1 class_2`, indicating that it is filtered through `document.querySelector` with `. Page-Title`, if there are two classes of `class_1 class_2` in the element at the same time, clean it up, otherwise supplement the non-existent class. In the test mode, because the event may be triggered twice (React mechanism), this setting will be converted twice, so it may not be effective on the surface
- Trick2.2 add, When the corresponding value is set to a string and begins with `css add##`, it indicates the `css class` additional mode, and the setting format is the same as `css##`
- Trick2.2 add, When the corresponding value is set to a string and begins with `css remove##`, it indicates the `css class` cleanup mode, and the setting format is the same as `css##`
- Trick2.2 add, When the corresponding value is set to a string and begins with `style##`, it indicates the `style` style setting mode. The element filtering setting and `style setting` are separated by `>>`, and multiple style settings are separated by `;`, such as `style##. Page-Title>>color:#fff;width:100%! Important;`, indicating that it is filtered through `document.querySelector` with`. Page-Title`, and set the style
- When the corresponding value is set to a string, it means to call other components or the function of page Action in the way of `id`. And the function of page Action begins with `act##`, such as `act##Language_Change`

- When the corresponding value is a function, it means that this function is called. This type is used for component testing. When making pages, this type cannot be used

- When the corresponding value is the object `{}`, it indicates the detailed setting. In general, when the event is called back, the returned data is the data of the whole component. If you want to configure the returned data in detail, the object type should be adopted; the fixed format is `{"_call":"",_data":{}} `,`_call` corresponds to the setting of the callback target, and `_data` corresponds to the setting of specific callback data; `_data` fixed format is `{"key 1":"value 1","key 2":"value 2"}`,  the `value` corresponding to the outermost `key` supports dynamic injection syntax; the dynamic syntax of `value` is that the beginning of `get##` means that it is obtained from the data of this component, and the beginning of `pack##` means that it is obtained from the data passed by `Pack component`, and it is allowed to use `>>` to locate deep data, such as `get## Key_1>>key_2`

- When the corresponding value is the array `[]`, the above types can be embedded, and the component will execute multiple callbacks (asynchronous calls, the order cannot be guaranteed)
- Trick2.2 added. By default, the `event` will be bubbled and passed (the upper HTML node will also respond). If you want not to bubble and pass, you can use the `_isStop` setting, `{"_isStop":true,"_call":"xxx "}`. If you want to set multiple callbacks, you can set it to `{"_isStop":true,"_call":["xxx", "xxx"]}`. If the bubble transmission is turned off, the `a` capture of the SPA web page by `_BoxPage` will also be invalidated

# ※ set-modify component settings

Add version: Component general mechanism

The parameters passed by the modified component are the same as `Config settings`, and the data that does not need to be updated can be omitted

- If the data is an array `[]` , and you want it to be an additional mode, add the `push##` prefix before `key`, such as `push##key`

- If the data is an array `[]` and you only want to replace the data at a certain position, then append the prefix `push##index##` before `key`, for example, `push##1##key`

- If the data is the object type `{}`, by default, the component will supplement and merge the omitted fields. If you do not want to merge the old settings, you can add the prefix `nec##` before `key`

- The prefix `nec##` and `push##` cannot exist at the same time

- The above prefix is only applicable to the `key` of the outermost layer of the `config` object
- If the newly set value does not match the type requirements, it will be replaced with the default value of the component instead of retaining the initialized component settings

### > Page Action Call Example

`Page Action` needs to use the `_BrokerUI` module for component settings, where `_config` corresponds to the set data

```
{
    "name":"_BrokerUI",
    "param":{
        "_id":"component id",
        "_config":{
        	"key":"value"
        }
    }
}
```

Supplementary note:

In the `_config` setting, the `value` corresponding to the outermost `key` supports module parameter syntax, such as `{"key":"get##$value"}`, which means that `$value` is obtained from `passParam`

- If you want to set the value to a fixed value, you can directly set the value of the corresponding type

- If you want to dynamically obtain the value from `passParam` as the setting value, please use `get##key` as the setting value

- If the value you want to get is in the inlayer layer (nested json) of `passParam`, please locate it with `>>`, such as `get##key_1>>key_2`

### > Page UI call example

If you want to update this component's settings when other component events are triggered. You can set the following parameters in the event callback of the corresponding component, where `_data` corresponds to the data of the settings

```
"_onXXX"：{
    "_call":"component id"
    "_data":{
        "key":"value"
    }
}
```

Supplementary note:

In the `_data` setting, the `value` corresponding to the outermost `key` supports dynamic injection syntax, such as `{"key":"get##key 1"}`, which means that the data of `key 1` is obtained from the component data that triggers the callback.

- If you want to get the value from the component data that triggers the callback, start with `get##`

- If you want to get the value from the data passed by the upper `Pack component` of the component that triggers the callback, use `pack##` to begin with

- When using `get##` and `pack##` at the beginning, it is allowed to use `>>` to locate deep data, such as `get##key_1>>key_2`

- Dynamic injection syntax is only suitable for the setting of the outermost value of the `_data` object, and the deep settings will not be processed

```
{
	"key 1":"get##key 1",         #dynamic injection value
	"key 2":{
  		"Key 2-1":"get##key 2"    #keep the value of 'get##key 2'
  }
}

```

# ※ get-get component data

Add version: Component general mechanism

`Page Action` needs to use the `_BrokerUI` module for getting component data, and the returned data is all the data in the above `config settings`

The data will be automatically inserted into `passParam`, and the inserted field is the value corresponding to `_resultKey`. When the corresponding value of `_resultKey` is an empty string `""`, the entire `passParam` will be emptied and the data will be written

```
{
    "name":"_BrokerUI",
    "param":{
    	"_id":"component id",
        "_isFailResend":false,
        "_isSync":true,
        "_config":{
            "_action":"get",
            "_resultKey":""
        }
     }
}
```

# ◎ Module separate test

In the root directory of the project, run the shell command

```
Python3 Christmas/Christmas.py ShellExcute/Build#Component @@name@@

```

You can also run `ShellExcute>>Build#Component` through `Christmas plug-in` and enter `@@name@@` in the terminal where the plug-in is opened

`Sample.html`, `Sample.js` is a code specifically for separate testing

# ◎ Updated list

**1.0=0000.00.00**

- Component create
######README-en######